Improve research projects with Quarto

Case of study

2025-07-03

1 Outline

Slides available online
https://vhgauto.github.io/seminario2-gulich/

2 Introduction

Research project

To estimate water quality indicators in Paraná River middle basin for algorithm development using satellite remote sensing techniques

Collaborative website with automatic update, interactive and open source.

2.1 Front page

  • Authors
  • Affiliation
  • Other format (.pdf by typst)
  • Last modified date
  • Abstract
  • Keywords
  • More resources links

2.2 Table of content

  • Sections and subsections
  • Easy website navigation
  • Variable content according to the progress development

2.3 Notebooks

  • Source code description to promote reproducibility
  • Processing data methodology
  • External resources for further reading

2.4 References

  • Formatted references according to desired style (.csl)
  • Reference preview on main text

2.5 Maps, tables & interactive plots

  • Results visualization
  • Correlation between parameters exploration
  • Spectral properties description
  • Sample site location

Maps, tables and figures are updated automatically upon new measurements

2.6 Custom styling

Lato |JetBrains Mono

Libre Bodoni |Bebas Neue

  • Accent colors


https://vhgauto.quarto.pub/gistaq-parana/

3 Motivation

Research Project progress.

%%{
  init: {
    'themeVariables': {
      'edgeLabelBackground': '#224289'
    }
  }
}%%

flowchart LR
    a1[Project<br>formulation] ==> a2[Start]
    a2 ====> |<span class="eos-icons--rotating-gear"></span>| a3[Main goal<br>is achieved]

    a3 ==> a4([Paper])
    a3 ==> a5([Conference])
    a3 ==> a6([Report])

classDef default stroke:#FFC0CB,color:#FFFFFF,fill:#224289;

  • Water sampling
  • Physicochemical analyses
  • Partial results assessment
  • Reference reading
  • Other tasks

While doing the Project, we lost vision on all the data collected and the knowledge acquired. Near the end we recognize this.

3.1 An alternative should be a…

  • Dynamic document to pour all the work, as is being made.

  • Flexible, so its adapts to the current project state.

  • Accesible, to check the latest results.

  • Easy to share with colleagues and third parties.

  • Unified reference search.

  • Automatically updated with new data, affecting plots, maps and tables.

  • Reproducible, with the entire script codes available.

  • All project members can work seamlessly without sync conflicts.

  • Consultation reference resource and to admire all the effort done so far.

  • Inspiration material for future papers and congress presentations.

4 Tools

  • R & Python: reading and data collection; processing and results storage; plots, tables and maps generation.

  • Git & GitHub: version control management and project members collaboration.

  • Quarto: to gather all the content in a website and to publish.

    • Manuscript allows website creation with emphasis in reproducibility and targeted to scientific and academic documents.

4.1 R

targets allows automatic functions execution and dependencies management between them.

Check current workflow state and execute only outdated targets.

File monitoring and code re-execution upon change detection.

4.2 R

graph LR
  x2eb57580dd338e28(["excel"]) ==> x75ae8feee719d1e2(["datos_gis"])
  x27cf98eb0536b3cc(["fecha_actual"]) ==> x75ae8feee719d1e2(["datos_gis"])
  x0dc39fa9e42347ba>"reflectancia"] ==> x75ae8feee719d1e2(["datos_gis"])
  x2eb57580dd338e28(["excel"]) ==> x1a91c1978c7a143b(["datos_lab"])
  x38637a02f9b83fc8>"lab"] ==> x1a91c1978c7a143b(["datos_lab"])
  x29bd13377b9e6171>"archivo_excel"] ==> x2eb57580dd338e28(["excel"])
  x2eb57580dd338e28(["excel"]) ==> x27cf98eb0536b3cc(["fecha_actual"])
  xfabd587be49f2fed>"fecha"] ==> x27cf98eb0536b3cc(["fecha_actual"])
  xfabd587be49f2fed>"fecha"] ==> x38637a02f9b83fc8>"lab"]
  xc36834a08989fd92>"archivo_quarto"] ==> x0cceab94dc3cb992(["manuscrito"])
  xc856c5bfddbb40a5{{"bandas_s2"}} ==> xc5ec810879cc40ee>"recorte"]
  x9505d3eeeff3a790{{"puntos_muestreo"}} ==> xc5ec810879cc40ee>"recorte"]
  x27cf98eb0536b3cc(["fecha_actual"]) ==> x4b150ba8dbe4203d(["recorte_tif"])
  xc5ec810879cc40ee>"recorte"] ==> x4b150ba8dbe4203d(["recorte_tif"])
  x3d474db92cf09724>"mensaje"] ==> x0dc39fa9e42347ba>"reflectancia"]
  xfabd587be49f2fed>"fecha"] ==> x0dc39fa9e42347ba>"reflectancia"]
  xcac90a77a625823f(["render_manuscrito"])
  
  classDef default stroke:#FFC0CB,color:#FFFFFF,fill:#224289;

4.3 R

renv for environment management, listing packages and dependencies.

Log file (renv.lock) that allows environment reproducibility, with package version and location repository. Only for R packages.

4.4 R

tidyverse for general purpose data processing and manipulation.

terra for geographic data processing and reading/writing of vector/raster .

4.5 R

ggplot2 for basic static plots (.png).

ggiraph for interactive plots (.html), with more data on hover.

leaflet for interactive map creation (.html).

4.6 PYTHON

  • Collection
  • Processing level
  • Region of interest
  • Time range
  • Credentials

4.7 GIT

Version control management and simultaneous collaboration between project members.

GitHub for cloud storage service, sharing and project repository.

branch per member, so each one works in a specific section without interfering with the remaining repository.

pull request to request change inclusion.

merge to combine changes once checked and accepted.

4.8 QUARTO

  • Combines code execution from programming language and narrative text to create a output file in multiple formatted options.

  • Offers a publishing platform (Quarto pub) for the output as a website.

%%{
  init: {
    'themeVariables': {
      'edgeLabelBackground': '#224289',
      'edgeLabel': 'red'
    }
  }
}%%

flowchart LR
  s1[<span class="ant-design--code-filled"></span><br>scripts]:::e1 ==> q1[<span class="simple-icons--quarto"></span><br>quarto]:::e1

  s2[<span class="material-symbols--markdown"></span><br>markdown]:::e1 ===> q1

  s3[<span class="fe--document"></span><br>text]:::e1 ===> q1

  s4[<span class="file-icons--latex"></span>]:::e1 ==> q1

  q1 ==> h1[<span class="bytesize--book"></span> <span class="lineicons--www"></span><br>
            <span class="majesticons--presentation"></span> <span class="ic--round-dashboard"></span><br>
            <span class="carbon--pdf"></span> <span class="carbon--html"></span><br>
            <span class="carbon--doc"></span> <span class="carbon--ppt"></span>]:::e1

  h1 ==>|<b style='color:white'>quarto pub</b>| w1[<span class="mdi--web"></span><br>website]:::e1

  classDef e1 stroke:none,color:#FFFFFF,fill:none;

4.9 QUARTO

4.10 QUARTO

  • Manuscript is design for scientific document authoring, with emphasis in reproducibility, since it encourages the readers to explore processing scripts (notebooks).

  • Offers multiple static outputs (.pdf, .docx) that can follow a specific template.

  • It allows to deploy the website in Quarto Pub or GitHub Pages .

  • In combination with targets, plots/tables/maps are regenerated with new data input, or script modification, updating the results.

4.11 QUARTO

Files and directory tree.

quarto_manuscript
├── bibliography/
│ ├── ieee.csl
│ └── reference.bib
├── data/
│ ├── laboratory.csv
│ └── reflectance.csv
├── plots/
│ ├── boxplot.png
│ └── time_series.png
├── notebooks/
│ ├── plots.qmd
│ └── data_reading.qmd
├── raster/
├── scripts/
│ ├── functions.R
│ └── support.R
├── vectors/
├── _publish.yml
├── _quarto.yml
├── _targets.R
└── manuscript.qmd

4.12 QUARTO

_quarto.yml
project:
  type: manuscript

manuscript:
  article: manuscrito.qmd
  notebooks:
    - notebooks/data_reading.qmd

format:
  html:
    lang: es
    include-in-header:
      - extras/favicon.html
    theme:
      - extras/my_style.scss
    toc: true
    code-link: true
    code-copy: true
    tbl-cap-location: margin
    fig-cap-location: bottom
    bibliography: bibliography/reference.bib
    csl: bibliography/ieee.csl
    html-math-method: katex
manuscript.qmd
---
title: Research Project
author: Víctor Gauto
date: last modified
---

# Introducción

**Paraná River** has <i>water</i>.

````{r}
ggplot(data, aes(x, y)) +
  geom_point()
````


_publish.yml
- source: project
  quarto-pub:
    - id: ff90d76c-20c0-4210-8791-5d868ede4c50
      url: https://vhgauto.quarto.pub/gistaq-parana

5 Conclusion

  • A Project website was developed using Quarto Manuscript.

  • By combining multiple tools, the website content is updated automatically and publish.

  • Project members participate in the development, in charge of their own sections.

  • We can check the Project progress and be proud of what is done and plan what is left.

5.1 Tools learned

The website creation alongside the Project development allowed us to learn a new set of tools.

6 Future improvements

  • Rewrite functions used by targets.
    • Define arguments clearly.
    • Return descriptive messages during runtime and in case of errors.
    • Incorporate website rendering.
  • Optimize satellite data download, avoiding to get the entire product.
    • Google Earth Engine.
    •  rsi package.
  • Organice website visual features (colors, fonts, styles, margins) in the .scss file.
  • Use the full potential of Manuscript, so the results are created by the notebooks.

Thanks for your time


7 Resources

Reproducible Manuscripts with Quarto - posit::conf(2023)

Quarto for Academics | Mine Çetinkaya-Rundel

Quarto | Get started

Quarto Manuscripts

Quarto Pub - Publishing service for Quarto documents

The {targets} R package user manual

Introduction to renv

R for Data Science (2e)

ggiraph-book

Quarto: The Definitive Guide

Website repository

Quarto Extensions

Official repository for Citation Style Language (CSL) citation styles